topic-axum
4. 与其他卡片的关联
- 前置卡片：
- 后续卡片：
- 相似主题：
1. 核心观点
Ⅰ. 概念层
Ⅱ. 应用层
Ⅲ. 实现层
IV.原理层
2. 背景/出处
- 来源：
- 引文/摘要：
- …
- …
3. 展开说明
基础概念
概念
- 生态兼容性: 完全兼容 tower 生态系统，tower 是 Rust 中强大的服务抽象层，定义了 Service trait 标准接口
- 中间件优势: 直接复用 tower-http 生态的中间件（超时、追踪、压缩、鉴权等），无需自行开发
- 互操作性: 可与 hyper 或 tonic 等基于 tower 的框架共享中间件，实现无缝集成
- 设计理念: 采用 " 服务即 trait" 的设计模式，所有组件都实现 Service trait 保证一致性
Axum 的互操作性与模块化设计
- GRPC 集成: 与 tonic（Rust 的 GRPC 实现）互操作方便，共享 hyper 和 tower 底层
- 混合部署: 支持与 AWS smithy 等 HTTP 服务共存于同一应用，路由可灵活分配
- 模块化架构: 通过 tower::Service 抽象实现高度解耦，各组件可独立替换，见 Rust-crate-tower-基本概念-TOC
- 生态定位: 作为 hyper 的上层封装，保持轻量级的同时提供完整 Web 框架功能
基本原理
监听器接受连接，hyper 是 http 库，将原始字节解析为 http 请求，axum 的路由器会将路径和方法与处理程序进行匹配。提取器从请求中提取数据，你的处理器正在运行，返回值通过 into Response 转换为响应。hyper 将字节流发送给客户端。所有的一切都是异步进行的。
基本使用介绍
- 核心特性：Rust 异步 web 框架，基于 tower 生态和 hyper 实现
- 路由系统：
- 使用 Router 构建请求路由
- 支持路径参数匹配（如/:id）
- 示例：route("/:id", get(handler))
- 请求处理：
- 通过 Handler trait 定义异步处理函数
- 支持提取器模式：Path、Json、State、Query
- 示例：
async fn handler(Path(id): Path<String>)
- 响应转换：
- 实现 IntoResponse trait
- 内置 Json 响应包装器
- 支持自定义状态码和 content-type
添加依赖
cargo add axum -F http2,query,tracing,headers
Axum 的性能与安全性
-
性能表现: 作为 hyper 的薄封装层，性能与 hyper 基本一致（平均延迟 0.65ms）
-
稳定性: 延迟标准差仅 0.36ms，远低于 actix-web 的 0.92ms，表现更稳定
-
安全保证: 使用#![forbid(unsafe_code)] 强制全安全 Rust 实现，无内存安全风险
-
性能对比：axum 与其他框架
- 最稳定。这两者性能几乎一致（axum 基于 hyper）。它们的标准差（Stdev）最低，最大延迟也最低（约 13-16ms），说明性能曲线非常平滑，极少出现卡顿。
- 第一梯队: actix-web(933k)、axum(768k)、hyper(768k) 属于性能第一阵营
- 延迟分布: axum 最大延迟仅 16.41ms，远优于 actix-web 的 152.70ms
- 综合测试: 在复杂场景下达到 143k 请求/秒，与 actix-web 的 184k 差距不大
- 选择考量: 牺牲少量性能换取更好的安全性（无 unsafe 代码）和开发体验
-
https://web-frameworks-benchmark.netlify.app/result?asc=0&l=rust&order_by=level512
处理 Handler 的参数
调试
- 所有 handler 的错误都和函数签名有关系
- 忘记添加 async 关键字导致 Handler trait 不满足
- 错误信息："the trait bound `fn() -> &'static str {index_hanlder}: Handler<,> is not satisfied"
完整索引
基于
note/atomic/目录的完整思维导图。
1. 入门
2. SOP
3. axum源码走读
4. feature
5. test
6. 代码和案例
7. 关联crate
8. 核心组件
8.1 handler
8.2 extractors
8.2.4 源码
8.3 layer
8.4 path
8.5 request
8.6 response
8.7 router
8.8 extentions
4. 应用/启发
- 可以如何应用在工作、学习、生活中
- 引发的思考与问题
5. 待办/进一步探索
- 聊天服务
- 微服务
- axum0.8：
- rust web 10x 最佳实践代码案例
- 文档阅读
- 可能有用的资料